﻿<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">

	<head>
		<meta content="text/html; charset=utf-8" http-equiv="Content-Type" />
		<title>Embedded Resource Files</title>
		<link href="bootstrap.min.css" type="text/css" rel="stylesheet" />
	</head>

	<body>

		<div class="document-contents">

			<h3 id="DocIntro">Introduction</h3>
			<p>ASP.NET Boilerplate provides an easy way of using embedded
			<strong>Razor views</strong> (.cshtml files) and <strong>other 
			resources</strong> (css, js, img... files) in your web application. 
			You can use this feature to create <a href="Module-System.html">
			plugins/modules</a> that contains UI functionality.</p>

			<h3 id="DocCreateFiles">Create Embedded Files</h3>
			<p>First, we should create a file and mark it as <strong>embedded 
resource</strong>. Any assembly can contain embedded resource files. The 
			progress changes based on your project format.</p>
			<h4>xproj/project.json Format</h4>
			<p>Assume that we have a project, named EmbeddedPlugIn, as shown 
			below:</p>
			<p>
			<img class="img-thumbnail" alt="Embedded resource sample project" height="295" src="images/embedded-resource-project-xproj.png" width="168" /></p>
			<p>To make <strong>all files</strong> embedded resource under
			<strong>Views</strong> folder, we can 
			add such a configuration to <strong>project.json</strong>:</p>
			<pre lang="js">  "buildOptions": {
    "embed": {
      "include": [
        "Views/**/*.*"
      ]
    }
  }</pre>
			<h4>csproj Format</h4>
			<p>Assume that we have a project, named EmbeddedPlugIn, as shown 
			below:</p>

			<p>
				&nbsp;<img class="img-thumbnail" alt="Embedded resource project structure" height="269" src="images/embedded-resource-project-csproj.png" width="201" /></p>
			<p>I select <strong>Index.cshtml</strong> file, go to properties window 
(F4 as shortcut) and change it's <strong>Build Action</strong> to <strong>
			Embedded Resource</strong>.</p>
			<p><img class="img-thumbnail" alt="Embedding a file into a c# project" height="240" src="images/embedded-resource-sample-file-csproj.png" width="254" /></p>
			<p>
You should change build action to <strong>embedded resource</strong> for <strong>all</strong> 
files you want to use in a web application.</p>

			<h3 id="DocExposeFiles">Add To Embedded Resource Manager</h3>
			<p>Once we embed our files into the assembly, we can use
			<a href="Startup-Configuration.html">startup configuration</a> to 
			add them to embedded resource manager. You can add such a line to 
			PreInitialize method of your <a href="Module-System.html">module</a>:</p>
			<pre lang="cs">Configuration.EmbeddedResources.Sources.Add(
    new EmbeddedResourceSet(
        <strong>"/Views/"</strong>,
        Assembly.GetExecutingAssembly(),
        <strong>"EmbeddedPlugIn.Views"</strong>
    )
);</pre>
			<p>Let's explain parameters:</p>
			<ul>
				<li>First parameter defines <strong>root folder</strong> for files 
				(like http://yourdomain.com<strong>/Views/</strong> here). It 
	matches to root namespace.</li>
				<li>Second parameter defines the <strong>Assembly</strong> 
				contains files. This code should be located in the assembly 
				containing embedded files. Otherwise, you should change this 
				parameter accordingly. </li>
				<li>And the last one defines <strong>root namespace</strong> of files in the 
	assembly. This is the default namespace (generally, the assembly name) plus 'folders in the assembly' 
				joined by a dot.</li>
			</ul>

			<h3 id="DocConsumeFiles">Consume Embedded Views</h3>
			<p>For <strong>.cshtml</strong> files, it's straightforward to 
			return them from a Controller Action. BlogController in the 
			EmbeddedPlugIn assembly is shown below:</p>
			<pre lang="cs">using Abp.AspNetCore.Mvc.Controllers;
using Microsoft.AspNetCore.Mvc;

namespace EmbeddedPlugIn.Controllers
{
    public class BlogController : AbpController
    {
        public ActionResult Index()
        {
            <strong>return View();</strong>
        }
    }
}
</pre>
			<p>As you see, it's same as regular controllers and works as 
			expected.</p>
			<h3>Consume Embedded Resources</h3>
			<p>To consume embedded resources (js, css, img...), we can just use 
			them in our views as we normally do:</p>
			<pre lang="cs">@section Styles {
    &lt;link href="~/Views/Blog/Index.css" rel="stylesheet" /&gt;
}

@section Scripts
{
    &lt;script src="~/Views/Blog/Index.js"&gt;&lt;/script&gt;
}

&lt;h2 id="BlogTitle"&gt;Blog plugin!&lt;/h2&gt;</pre>
			<p>I assumes that the main application has Styles and Scripts 
			sections. We can also use othe files (like images) as normally we 
			do.</p>
			<h4>ASP.NET Core Configuration</h4>
			<p>ASP.NET MVC 5.x projects will automatically integrate to embedded 
			resource manager throught Owin (if your startup file contains 
			app.UseAbp() as expected). For ASP.NET Core projects, we should 
			manually add <strong>app.UseEmbeddedFiles()</strong> to the Startup 
			class, just after app.UseStaticFiles(), as shown below:</p>
			<pre lang="cs">app.UseStaticFiles();
<strong>app.UseEmbeddedFiles();</strong> //Allows to expose embedded files to the web!</pre>
			<h4>Ignored Files</h4>
			<p>Normally, <strong>all files</strong> in the embedded resource 
			manager can be directly consumed by clients as if they were static 
			files. You can ignore some file extensions for security and other 
			purposes. <strong>.cshtml</strong> and <strong>.config</strong> 
			files are ignored by default (for direct requests from clients). You 
			can add more extensions in PreInitialize of your module as shown 
			below:</p>
			<pre lang="cs">Configuration.Modules.AbpWebCommon().EmbeddedResources.<strong>IgnoredFileExtensions</strong>.Add("exe");</pre>
			<h3>Override Embedded Files</h3>
			<p>One important feature of embedded resource files is that they
			<strong>can be overrided</strong> by higher modules. That means you 
			can create a file with same name in the same folder in your web 
			application to override an embedded file (your file in the web 
			application does not require to be embedded resource, because static 
			files have priority over embedded files). Thus, you can override 
			css, js or view files of your modules/plugins in the application. 
			Also, if module A depends on module B and module A defines an 
			embedded resource with the same path, it can override an embedded 
			resource file of module B.</p>

		</div>

		<p>Notice that: For ASP.NET Core projects, you should put overriding 
		files to the wwwroot folder as the root path.</p>

	</body>

</html>